package com.linkgie.galaxyframework.kvstorage.spi;

import com.linkgie.galaxyframework.kvstorage.KVStorageException;
import com.linkgie.galaxyframework.kvstorage.KeyIterator;

public interface KVDataview {

	boolean contains(byte[] key) throws KVStorageException;

	byte[] get(byte[] key) throws KVStorageException;

	void set(byte[] key, byte[] value) throws KVStorageException;

	boolean insert(byte[] key, byte[] value) throws KVStorageException;

	boolean update(byte[] key, byte[] value) throws KVStorageException;

	/**
	 * 移除指定的键；
	 * 
	 * @param key
	 * @return
	 * @throws KVStorageException
	 */
	void delete(byte[] key) throws KVStorageException;

	/**
	 * 键的总数；
	 * <p>
	 * 
	 * 如果不支持检索总数，则返回 -1 ；
	 * 
	 * @return
	 */
	long getKeyCount();

//	/**
//	 * 扫描指定前缀的所有键；
//	 * 
//	 * 返回一个迭代器扫描以指定前缀开头所有的键值；
//	 * 
//	 * 实现者应遵循以下规则：<br>
//	 * 
//	 * 1. 实现规范不定义对键值扫描的顺序，实现者可以自行决定任意的顺序策略，但应保证迭代器中同一个键只出现 1 次。
//	 * 
//	 * 2. 如果不支持扫描，或者仓库已关闭（{@link #isAlived()} 返回 false），则抛出
//	 * {@link OperationNotSupportedException} 异常；<br>
//	 * 
//	 * @param prefix 要检索的前缀；只有包含此前缀的键被包含在迭代范围；
//	 * @return
//	 */
//	KeyIterator<byte[], byte[]> seekPrefix(byte[] prefix);

	/**
	 * 按指定的范围进行前向搜索遍历；
	 * 
	 * @param beginPrefix 起始键前缀；
	 * @param excludedStart  是否排除“起始键前缀”所命中的内容；注意，不只是 beginPrefix 指定的值，而是以此为前缀的整个数值空间；
	 * @param endPrefix   截止键前缀；
	 * @param excludedEnd    是否排除“截止键前缀”所命中的内容；注意，不只是 endPrefix 指定的值，而是以此为前缀的整个数值空间；
	 * @return
	 */
	KeyIterator<byte[], byte[]> forwardPrefixSeek(byte[] beginPrefix, boolean excludedStart, byte[] endPrefix,
			boolean excludedEnd);
	
	/**
	 * 按指定的范围进行后向搜索遍历；
	 * 
	 * @param beginPrefix 起始键前缀；
	 * @param excludedStart  是否排除“起始键前缀”所命中的内容；注意，不只是 beginPrefix 指定的值，而是以此为前缀的整个数值空间；
	 * @param endPrefix   截止键前缀；
	 * @param excludedEnd    是否排除“截止键前缀”所命中的内容；注意，不只是 endPrefix 指定的值，而是以此为前缀的整个数值空间；
	 * @return
	 */
	KeyIterator<byte[], byte[]> backwardPrefixSeek(byte[] beginPrefix, boolean excludedStart, byte[] endPrefix,
			boolean excludedEnd);

}